\documentclass[a4paper,10pt]{article}
\usepackage[utf8x]{inputenc}
\usepackage[cm]{fullpage}

%opening
\title{Course Diary - Entry \#3\\
475 Advanced Topics in Software Engineering}
\author{Eli Gutin \texttt{eg08}, \\ Michael Kwan \texttt{mk08}, \\ John Wong \texttt{jw808} }

\begin{document}

\maketitle

\section{Three key points from the lecture}

\begin{itemize} 
\item{A DSL is a specialised language that is used within a specific problem domain. You can write either your own from scratch (external DSLs) which requires more work but gives you flexibility. Alternatively, it's possible
to create one within an application that is written in an existing mainstram language (internal DSLs).}
\item{APIs can be categorised as either a \textit{command-query} API or a \textit{fluent interface}. The latter aids in bridging the gap between technical low-level concerns and business logic and goals. The fluent interface is 
an internal DSL.}
\item{We looked at a practical example of DSLs in Java. This was done using builder classes that encapsulated how the target object was to be built and used method chaining. After each call a narrower interface is employed
to guide the user and achieve the language's grammar. 
Related to that we learned that primitive types should never really be passed in as parameters and should instead be wrapped up in objects.}
\end{itemize}

\section{Related Reading}
An article we came across by Martin Fowler \texttt{http://martinfowler.com/bliki/FluentInterface.html} was particularly relevant. There he describes what was, at the time, a fairly new style of writing APIs.
It was the use of method naming and method chaining that would make the code look fluent and is classed as an internal DSL. Martin notes that there are potential downsides to this such as an object having a 
method name that doesn't make sense outside of the intended context (e.g. \texttt{with}). Another downside he mentions is that setter methods should really be of type \texttt{void} 
and not return back a reference to the object it was modifying. The convention is common in the \textit{command query} style of coding but Martin concludes that it might be worth sacrificing this convention
 in order to gain readability. A final possible drawback described from the article is that this is considerably more time consuming and requires more thought than just using classic constructors and JavaBean setters.
Apart from those possible disadvantages Martin said that it was worth experimenting with this as it has been successful in the past (e.g. \texttt{jMock}) among others.
What we took away from this article was a balanced and critical perspective on the pattern. It made us think more carefully about when we should really apply it (the article gives the construction of value objects as
one example of a good use).

'An exploration of program as language' by Banissad and Myers, discusses the implicit semantic implications that can be interpreted from code and hence the concept that program code 
can express 'meaning to other humans, not to the compiler'. In essence, the article discusses the gap between program semantics and code semantics. One way programmers attempt 
to bridge this gap is through the use of abstractions and design patterns. During these attempts, programmers sometimes create DSLs, formal rules and constraints for a new 'language'. 
The article is careful to distinguish and draw the line between DSLs and program language. In our opinion, the authors give an interesting perspective to programming, formalising ideas 
and concepts which might seem inherently obvious on the surface but underlyingly demonstrating their appreciation of code from a different angle. Reading the article has changed my 
viewpoint somewhat, leading me to believe my previous inspection and judgement of code has perhaps been pedantically skewed looking at the level of technical expertise.

There is another webpage which we thought it is interesting to go through: \\ \texttt{http://www.valibuk.net/2009/03/domain-specific-languages-in-ruby/}, which shows how to create a DSL using an existing language - Ruby. 
The website goes through the process of bulding a Ruby program which recognises DSLs with an example class \texttt{Tape}, which is defined with a state, tape content and head position. 
It then defines all the DSL commands such as \texttt{write, load, push, dump,}etc. In the end, the program can read scripts such as follows: \\ \texttt{write 1, dump, right, write 2, dump, left, left, write 3, dump} 
\\With this DSL commands combined with Ruby, it's possible to write up a ruby program which has a better degree of fluent interface. \\(e.g. \texttt{(1..5).each do |i| (write i, right, dump, end})

\section{Similar Past Projects}
\subsection{Mike's experience}
During my Industrial Placement, my main project was to build a framework which worked on top of the Selenium 2.0/WebDriver library. I wanted to produce an API similar in nature to Selenium's; terse, succinct and easy to pick up. 
Selenium employs an \texttt{Actions} class to chain many complex sequences of page actions together, before building it to produce an \texttt{Action} object. which is more simply reusable. Another example with how Selenium uses the builder pattern 
is in one of the recommended design patterns for writing Selenium tests: Page Objects. In this design pattern, the author recommends treating each page as an object. Therefore, every action on a page returns some other page object, 
whether that be itself or a page to which it has navigated to. 

Even though much of the Selenium API is already modelled in a DSL style, an extreme case of it is the \texttt{HamcrestWebDriverTestCase} class which allows \texttt{WebDriver} tests to be written in a LiFT style (e.g. using the Finder classes). 
For my project, I incorporated this class and extended it to be part of my final framework.

\subsection{Eli's experience}
A good example that I have come across of the DSL patterns, described in the lectures, was from the \texttt{Mockito} and \texttt{jMock} APIs. I have worked extensively with the former and I enjoyed the fact that I was able to deduce the correct usage just
from the auto-complete feature of my IDE. I was able to appreciate how making the code as 'English' as possible makes the project easier to work with and hence manageable in the long run. The reason being that each developer can quickly find a fault
just by reading and thinking about the code as they would by describing it. This was evident from both my own experience and that of people who reviewed my code.

My experience involved implementing a small \textit{external} DSL which was a boolean expression parser/interpreter. It was part of a much larger project and its purpose was to store subscriptions 
to email notifications based on certain criteria and their combination. The kind of expressions that it could understand and process were specific to the problem domain, for example, to only notify a user regarding
specific accounts or products. This demonstrated to me that designing small grammars and languages is inevitable when working as a developer since these approaches are often the best solutions to a multitude of use cases.
\subsection{John's experience} 
I've used a lot of Java libraries during my study and personal project developments, and there were a few which I found it easy to adapt to. 
I then discovered that the reason for this is that they all have a fluent API, which act like an internal DSL in Java. 
I realised that this style of API gives you a better and quicker understanding of most informations about the new object type such as behaviours, statuses and the usages.
This also prevents a lot of frustrations from finding semantic errors and bugs since those APIs provide a much more readable code.


\section{Tutorial Exercise Description}
The tutorial exercise was based on an existing project simulating various bidders using different strategies to try to win at an auction. Unit tests existed which instantiated and configured these bidders, finally pitting them 
against each other at simulated auctions. The aim was to change the way that different bidders are created and/or configured in the code such that it is more readable. It was suggested the implementation of a DSL could be used to 
achieve this. For example the original code had \texttt{withBidder(bidder("fred", gbp(10), gbp(10), gbp(10000)))} and the aim was to make it read more like
\textit{with bidder named ``fred'' who bids from £10 up £10000 in increments of £10}

\section{Main Challenges}
One challenge we faced during this week's exercise was attempting to find an efficient way to refactor the \texttt{int} values for prices into our \texttt{Money} objects. 
Even though it is easy to rename variables using the IDE, it is much harder to globally change the type of an object. In fact, after some investigation we ended up having to perform 
the refactorings mostly manually. After speaking to one of the tutorial helpers, we found eclipse's refactoring tool does not support 'type replacement' although there is apparently 
internal tooling at IBM to do this. In this case, Ctrl-Shift-G was useful to find the references to the variable we were interested in changing.

Another challenge was that we had to consider carefully the structure of our builder pattern. At the same time as making sure the code worked as it should, we had to try 
to make the API calls as \emph{fluent} as possible. As well this the composition of our builders had to be such that the correct set of parameters would be passed in, for example
, an incrementing bidder would first need a name, then a starting bid, a increment and finally a limit. This wasn't a trivial task as we were relatively new to this style.
\section{Approaches}
The first decision we made was to store money/price as \texttt{Money} objects instead of \texttt{int} values. The reason for this was because we needed to encapsulate
and keep the logic related to prices (or possibly wealth) in one place. It could for example be useful if we needed to change the internal representation of 'money'.
Furthermore, this would allow for the possibility of currency exchange, even though this was not a current requirement. Another major advantage of having this abstraction was
that it becomes clearer to anyone working with the code what the purpose of the parameter was, whereas an \texttt{int} could represent the number of rounds, an index into an array or anything potentially.
We followed the example in the lecture by giving the \texttt{Money} class a private constructor which meant objects of that class could only be instantiated with the static factory methods provided.
As a result we could represent £50 as \texttt{Money.gbp(50)}. To complete the money class we found we needed to override the \texttt{compareTo/equals/hashCode} methods because prices were originally treated
as primitives with \texttt{==}, \texttt{<} operators (including arithmetic) and we needed to preserve the original logic.

The second difference with our DSL compared to the original code was more involved. 
We needed to define a language which we felt was more user-friendly and obvious to someone writing or reading the code. 
For example, the DSL we aimed to create would use the following expression for the first test: \\ \texttt{withBidder(\textit{named("fred")}.whoStartsAtBidOf(gbp(10)).andIncrementsIn(gbp(25)).upTo(gbp(10000)))}
The reason each of these methods had one argument was for simplicity. It can also be seen that each method name becomes a short description of what its argument is for.

To start implementing code to achieve this, we had to look at how the original code worked. Essentially, the original code had 4 private methods which proxied arguments to directly create the different types of bidder.
 We felt the style we adopted above allowed expression in a more intuitive manner as well as being hopefully able to support appropriate code completions. 

To implement the DSL above we implemented a builder class \texttt{ParticipantBuilder}. In it we created a static \texttt{\textit{named(String bidderName)}} method. This was imported statically in the test fixture and
when it was called it returned an instance of the builder class, from which the chained methods would be called and a bidder created from the provided name.
Our implementation made heavy use of the narrow interfaces pattern, presented in the lecture, to guide the user as to what methods were available at any point during chaining. We did in this way to make it easy for a user of our API to 
create a bidder without having to read up what dependencies it has. They would simply be guided by the IDE instead of having to look up, for example, what the constructor arguments are or what setters to call.
Furthermore, this was beneficial as it would prevent someone inadvertently creating an invalid bidder if they used the common approach. 
\section{Feedback on the lecture/excercise}

We think that the lecture contained quite informative details about the concept of DSL. It emphasized the usage of DSL and the reasons for using this technique when it comes to designing and programming code. 
Furthermore, it showed a clear description of the materials such as fluent interface, the factories and builder design patterns with code examples which helped a lot on demonstrating how it works and allowed us to grasp their usages quicker.
On the notes provided, there's another example of the those DSL techniques for us to take reference of which uses the same simple object class \texttt{Coffee} with the command \texttt{withMilk} and \texttt{withSugars} so that it emphasizes the difference in between.
We find this extremely useful to guide us through the tutorial exercise as well.
In terms of the exercise, the guidelines of the provided project were fairly simple and goals were layed out clearly, which allows us to proceed quickly to the main challenges.
One uncertainty that we weren't too clear about was whether we were supposed to manually modify all the money/price values used in this project into \texttt{Money} object when we intented to improve the internal representation of it.
This is because we were aware that this action is time-comsuming and risky (missing one instance modification could break the whole entire system). Eventually, we had it confirmed and made the tests in a working state. 

\end{document}
